home *** CD-ROM | disk | FTP | other *** search
.TH STACK .SH NAME Stack<Type>\f1 A dynamic, parameterized stack .SH SYNOPSIS #include <cool/Stack.h> .SH DESCRIPTION The \f3Stack<Type>\f1 class implements a conventional first-in, last-out datastructure that holds a user-specified data type. All memory management and initialization is encapsulated and performed by the class constructors and member functions. Stack objects can be either static-sized or dynamic. Stacks are, by default, dynamic in nature. A static-sized stack object is selected by setting the growth allocation size to zero or by passing in a pointer to a block of user-supplied storage to the constructor. If a stack is of static size and an operation is performed that requires more storage, an \f3\f3Error\f1\f1 exception is raised. .SH Base Classes Stack, .SH Friend Classes None .SH Constructors .TP \f3Stack<Type> ();\f1 Creates an empty stack of the specified type. .TP \f3Stack<Type> \f3(unisgned long \f2number\f3);\f1 Allocates enough storage for a stack of a specific type to hold number of elements. .TP \f3Stack<Type> (const Stack<Type>& stk\f3);\f1 Duplicates the size and value of a stack object stk . .TP \f3Stack<Type> (void* \f2storage\f3, unsigned long \f2number\f3);\f1 Creates a static-sized stack object for number of elements whose storage storage is provided by the user. If an object of this type attempts to grow dynamically or the programmer invokes the resize member function, an \f3\f3Error\f1\f1 exception is raised. .SH Member Functions .TP inline long capacity () const; Returns the maximum number of elements the stack can contain. .TP inline void clear (); Sets the number of elements in the stack to zero. .TP \f3Boolean find (const Type& value\f3);\f1 Searches the stack for value . If value is found, this function returns TRUE ; otherwise, this function returns FALSE . .TP inline Boolean is_empty () const; Returns TRUE if the stack has no elements; otherwise, this function returns FALSE . .TP inline long length () const; Returns the number of elements in the stack. .TP \f3Stack<Type>& \f3operator= (const Stack<Type>& stk\f3);\f1 Overloads the assignment operator for the \f3Stack<Type>\f1 class and assigns stk to the stack object by duplicating the size and element values. If the stack object is prohibited from dynamically growing, an \f3\f3Error\f1\f1 exception is raised. .TP \f3Boolean operator== (const Stack<Type>& stk\f3) const;\f1 Overloads the equality operator for the \f3Stack<Type>\f1 class. Returns TRUE if the stacks have an equal number of elements with the same values; otherwise this function returns FALSE . .TP \f3inline Boolean operator!= (const Stack<Type>& stk\f3) const;\f1 Overloads the inequality operator for the \f3Stack<Type>\f1 class. This function returns TRUE if the stacks have a unequal number of elements or unequal values; otherwise this function returns FALSE . .TP \f3inline Type& operator[\^] (unsigned long \f2number\f3);\f1 Overloads the index operator for the \f3Stack<Type>\f1 class. This function returns a reference to the element of the stack that is number of elements from the top of the stack. If number is greater than the size of the stack, an \f3\f3Error\f1\f1 exception is raised. .TP inline Type& pop (); Removes and returns a reference to the top element on the stack. If the number of elements (that is, length) has been set to a zero-relative index greater than the size of the stack, an \f3\f3Error\f1\f1 exception is raised. .TP \f3Type& popn (long \f2n\f3);\f1 Pops n elements off the stack, returning a reference to the last one popped off the stack. With an argument of zero, this function returns the top item of the stack without removing it. If the number of elements to pop is negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3long position (const Type& value\f3) const;\f1 Searches the stack for value . If value is found, this function returns the zero-relative index, from the top of the stack, of that element; otherwise, this function returns \-1. .TP \f3inline Boolean push (const Type& value\f3);\f1 Pushes value onto the top of a stack. If required and not prohibited, this function grows the stack object. This function returns TRUE if successful; otherwise, this function returns FALSE . If the stack is prohibited from growing dynamically, an \f3\f3Error\f1\f1 exception is raised. .TP \f3Boolean pushn (const Type& value\f3, long \f2n\f3);\f1 Pushes n items onto the top of the stack, all of which have the specified value . When n is zero, this function replaces the top item on the stack with value . If required and not prohibited, this function grows the stack object. This function returns TRUE if successful; otherwise, this function returns FALSE . If the stack is prohibited from growing dynamically, an \f3\f3Error\f1\f1 exception is raised. .TP \f3void resize (long \f2number\f3);\f1 Resizes the stack for at least number of elements. If a growth ratio has been selected and it satisfies the resize request, the stack is grown by this ratio. If the stack is prohibited from dynamically growing, an \f3\f3Error\f1\f1 exception is raised. .TP \f3inline void set_alloc_size (int \f2size\f3);\f1 Updates the allocation growth size to be used when the growth ratio is zero. Default allocation growth size is 100 bytes. Setting the allocation growth size to zero results in a static-sized object. If size is zero or negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3inline void set_compare (\f2Stack_Compare\f3 = NULL);\f1 Sets the compare function for this class of stack. Stack_Compare is a user-defined function of type Boolean (\f2*Function\f1)(\f3const Type&\f1, \f3const Type&\f1). If no such function is provided, the operator== for the type over which the class is parameterized is used. .TP \f3inline void set_growth_ratio (float \f2ratio\f3);\f1 Updates the growth ratio for this instance of a stack to ratio . When a stack needs to grow, the current size is multiplied by the ratio to determine the new size. If ratio is negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3inline long set_length (long \f2number\f3);\f1 Specifies the number of elements in a stack to allow random access via the overloaded operator[\^] member function. If number is larger than the storage allocated, this function truncates number to the largest value that the allocated size will support. This function returns the new element count. If number is negative, an \f3\f3Error\f1\f1 exception is raised. .TP inline Type& top (); Returns (without removing) a reference to the top element of the stack. If the number of elements (that is, length) has been set to a zero-relative index greater than the size of the stack, an \f3\f3Error\f1\f1 exception is raised. .SH Friend Functions .TP \f3friend ostream& operator<< (ostream& \f2os\f3, const Stack<Type>& stk\f3);\f1 Overloads the output operator for a reference to a \f3Stack<Type>\f1 object to provide a \p formatted output capability. .TP \f3inline friend ostream& operator<< (ostream& \f2os\f3, const Stack<Type>* stk\f3);\f1 Overloads the output operator for a pointer to a \f3Stack<Type>\f1 object to provide a \p formatted output capability. .SH COPYRIGHT Copyright (C) 1991 Texas Instruments Incorporated. Permission is granted to any individual or institution to use, copy, modify, and distribute this software, provided that this complete copyright and permission notice is maintained, intact, in all copies and supporting documentation. Texas Instruments Incorporated provides this software "as is" without express or implied warranty. 
